update boxd sandbox blueprint for @boxd-sh/sdk 0.2 - #642

Summary

Follow-up to #62. @boxd-sh/sdk 0.2 (0.2.7 at time of writing) replaced the 0.1.x handle-based API the boxd blueprint was written against, so this updates the integration to the latest SDK:

• blueprints/sandbox--boxd.md bumped to version 2: adapter rewritten against the new API, prose updated (@boxd-sh/sdk@^0.2.7, bxd_ key prefix, machines.fork tip), and a cumulative Upgrade Guide entry carrying the complete v1 → v2 unified diff per the blueprints/README.md contract. Validated with generate-blueprint-index.ts.
• apps/docs/.../ecosystem/sandboxes/boxd.md refreshed to match.

What changed in the SDK

0.2 is a full API rewrite, not an incremental bump:

• Client is Boxd (was Compute); the stateful Box handle is gone in favor of a flat client.machines.* namespace whose methods take the machine id.
• File transfer moved to machines.files.download / machines.files.upload.
• Exec takes a params object ({ command, env, timeout }); the timeout option was renamed from timeoutMs to timeout (still milliseconds).
• Statuses renamed (suspended, starting, migrating, …); the terminal set the death detector keys on (destroyed / failed / stopped) is unchanged.
• Unary calls now carry a 60s client deadline, but exec streams still carry none — so the adapter's in-flight death-detector poll is still required and is kept.

Adapter shape change

boxd(box, { client }) becomes boxd(client, machine, options?): the Boxd client is now a required first argument (every operation routes through it), so the death detector is always active instead of opt-in via options.client. The machine can be passed as the Machine record or its id. cwd, readyTimeoutMs, the /home/boxd default, and all SandboxDriver behavior are unchanged. The Upgrade Guide diff covers existing installs.

Verification

• Blueprint index generator validates the version-2 contract (frontmatter, marker, cumulative Upgrade Guide with unified diff) and regenerates the index with boxd at version 2.
• The verbatim adapter file typechecks cleanly (tsc --noEmit) against @boxd-sh/sdk@0.2.7 and @flue/runtime.
• Exercised end to end against a real boxd production VM through Flue's Sandbox interface (the same surface a model-invoked tool drives): 23/23 checks — readiness probe on a fresh machine, default cwd /home/boxd, shell coverage (compound commands, pipes, redirects, env forwarding with quoting, stderr/exit codes), file APIs including a binary round-trip via machines.files, stat/readdir/exists/mkdir/rm, exec timeout enforcement, and the death detector rejecting with SandboxDiedError ~5s after the machine was deleted mid-exec.
• Full agent loop verified with flue run: an agent using the generated adapter created a machine, the model called its sandbox tool, and all checks passed on the VM.

Test plan

• generate-blueprint-index.ts passes and lists boxd at version 2.
• Adapter typechecks against @boxd-sh/sdk@0.2.7.
• End-to-end against a real boxd VM (direct Sandbox interface + full flue run loop).
• After website rebuild on merge, https://flueframework.com/cli/blueprints/boxd.md serves the version-2 body.

🤖 Generated with Claude Code